home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / a86b.arc / XREF.DOC < prev   
Encoding:
Text File  |  1986-06-22  |  4.7 KB  |  101 lines
  1. ---XREF.DOC---
  2.  
  3. XREF Cross-reference and Symbol Listing Facility
  4.  
  5.  
  6. XREF is a tool that creates a cross-referenced symbol table listing of your
  7. program.
  8.  
  9. To invoke XREF, you must provide a program invocation line, either typed to the
  10. console when the DOS command prompt appears, or included in a batch file.  The
  11. program invocation line consists of the following:
  12.  
  13. 1. The program name XREF.
  14.  
  15. 2. The name of a symbol-table file produced by A86 when you assembled your
  16.    program.  If you do not give an extension, XREF assumes a .SYM extension;
  17.    if you wish no extension, you give a period without an extension.  Note that
  18.    if you follow normal methodology, the name of the symbol-table file is the
  19.    same as the name of the program.
  20.  
  21. 2. The same list of source-file names that you gave to A86.  Just as with A86,
  22.    you may use the wild-card delimiters * and ? if you wish, with the same
  23.    results.
  24.  
  25.    XREF, like A86, identifies the end of the source file names when it sees a
  26.    name with no extension, or a name with the default output-extension.  For
  27.    XREF, that extension is .XRF.
  28.  
  29. 3. You may optionally provide the word TO, to separate the source file names
  30.    from the output file names.
  31.  
  32. 4. The name of the output listing file.  If you do not provide an extension,
  33.    XREF will assume that you want the extension .XRF. If you want your program
  34.    file to have no extension, you end the file name with a period.
  35.  
  36.    You have the option to omit the output file name.  If you do, XREF will use
  37.    the name of the symbol-table file, with the extension .XRF.
  38.  
  39.  
  40. The output of XREF is an alphabetical listing of all the non-local symbols in
  41. your program.  For each symbol, XREF gives its type, the file in which it was
  42. defined, its value, and a list of all procedures in which the file was used.
  43. If you print this file, you typically use the TCOLS tool to obtain a multi-
  44. column listing from XREF's single-column output.
  45.  
  46. Note the use of procedure names to identify references -- this is unique to
  47. the A86 package, and makes the cross-reference listing truly readable.  Other
  48. cross-reference listings give either line numbers, which are meaningless
  49. unless you go find the associated line; or a file-name, which doesn't give
  50. you as much useful information.
  51.  
  52. Here is a more detailed description of the various pieces of information
  53. provided for each symbol:
  54.  
  55. 1. TYPE.  Labels are indicated by a colon immediately following the symbol-
  56.    name.  Macros are denoted by the word "macro" in place of the value on
  57.    the following line.  Other symbols types are described by one or two
  58.    characters, following the symbol name.  Possibilities for the first
  59.    character are:
  60.  
  61.         m  for a simple memory variable
  62.         +  for an index memory quantity
  63.         c  for a constant
  64.         i  for an interrupt-equate
  65.         s  for a structure
  66.  
  67.     If there is a second letter, it is a size attribute: b for byte, w for
  68.     word, f for far (or doubleword).
  69.  
  70. 2. FILE in which the symbol was defined.  The name is stripped of its
  71.    extension, which is presumably the same for all your source files.  The
  72.    name is preceded by = or period , which denotes a definition, not a
  73.    reference, of the symbol.
  74.  
  75. 3. VALUE, given as 4 hex bytes, on the line following the symbol.  For
  76.    memory variables, this is the location of the variable.  For indexed
  77.    quantities, this is the constant-displacement part of the quantity.
  78.    For structures, it is the size of the structure.  For interrupt-equates,
  79.    it is the number of the interrupt.
  80.  
  81. 4. REFERENCES, given on indented lines following the symbol name. All
  82.    occurances of the symbol in your program produce a reference.  If the
  83.    symbol is the first thing of a line, it is considered a "definition" of
  84.    that symbol, the reference listed is the source file name.  The name is
  85.    preceded by a period if the definition was via a colon (i.e., a label); it
  86.    is preceded by an equals-sign otherwise. If the symbol is not the first
  87.    thing of the line, then it is not a definition.  The reference-listing
  88.    consists of the name of the last definition that XREF scanned (which, if
  89.    your program is organized in a standard way, will be the name of the
  90.    procedure in which the reference occurred.
  91.  
  92.    Observe that you must use the local-label facility of A86 to make this
  93.    work.  If you don't use local-labels as your "place-marker" symbols,
  94.    the symbol XREF gives you will often be the name of the last "place-marker"
  95.    symbol, not the name of the last procedure.
  96.  
  97.    To save space, duplicate reference-entries are denoted by a single entry,
  98.    followed by "*n", where n is the decimal number of occurrances of that
  99.    entry.
  100.  
  101.